3D Graphics Programming with QuickDraw 3D 1.5.4

Extending Group Objects

QuickDraw 3D provides a programming interface by which you can add new group objects to the class TQ3GroupObject . This section first describes the Q3XGroup_GetPositionPrivate function, by which you can access the private data in your group object, and then lists the methods that may be called.

Q3XGroup_GetPositionPrivate

You can use the Q3XGroup_GetPositionPrivate function to return the private data stored in a group object.



 
void Q3XGroup_GetPositionPrivate (

                     TQ3GroupObject group,

                     TQ3GroupPosition position);

group: A group object.
position: A position in the group object.

DESCRIPTION

The Q3XGroup_GetPositionPrivate function returns the the private data stored at position position in group object group.

TQ3XGroupAcceptObjectMethod

The TQ3XGroupAcceptObjectMethod method reports whether a group will accept a particular object type.



 
TQ3Boolean (*TQ3XGroupAcceptObjectMethod) (

                     TQ3GroupObject group,

                     TQ3Object object);

group: A group object.
object: A new object to be placed in the group.

DESCRIPTION

The TQ3XGroupAcceptObjectMethod method returns TQ3True if the group object group will accept an object of type object and TQ3False otherwise.

TQ3XGroupAddObjectMethod

The TQ3XGroupAddObjectMethod method adds an object to a group.



 
TQ3GroupPosition (*TQ3XGroupAddObjectMethod) (

                     TQ3GroupObject group,

                     TQ3Object object);

group: A group object.
object: A new object to be placed in the group.

DESCRIPTION

The TQ3XGroupAddObjectMethod method adds the object object to the group group. It returns the position of the new object if successful and NULL otherwise.

TQ3XGroupAddObjectBeforeMethod

The TQ3XGroupAddObjectBeforeMethod method adds an object before a given position in a group.



 
TQ3GroupPosition (*TQ3XGroupAddObjectBeforeMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition position,

                     TQ3Object object);

group: A group object.
position: A position in a group object.
object: A new object to be placed in the group.

DESCRIPTION

The TQ3XGroupAddObjectBeforeMethod method adds the object object to the group group before the position position. It returns the position of the new object if successful and NULL otherwise.

TQ3XGroupAddObjectAfterMethod

The TQ3XGroupAddObjectAfterMethod method adds an object after a given position in a group.



 
TQ3GroupPosition (*TQ3XGroupAddObjectAfterMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition position,

                     TQ3Object object);

group: A group object.
position: A position in a group object.
object: A new object to be placed in the group.

DESCRIPTION

The TQ3XGroupAddObjectAfterMethod method adds the object object to the group group after the position position. It returns the position of the new object if successful and NULL otherwise.

TQ3XGroupSetPositionObjectMethod

The TQ3XGroupSetPositionObjectMethod method replaces an object in a group.



 
TQ3Status (*TQ3XGroupSetPositionObjectMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition gPos,

                     TQ3Object obj);

group: A group object.
gPos: A position in a group object.
obj: A new object to be placed in the group.

DESCRIPTION

The TQ3XGroupSetPositionObjectMethod method replaces the object currently at position gPos in the group group with the new object obj. It returns kQ3Success if successful and kQ3Failure if the given group position is not in the group.

TQ3XGroupRemovePositionMethod

The TQ3XGroupRemovePositionMethod method replaces an object in a group.



 
TQ3Object (*TQ3XGroupRemovePositionMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition position);

group: A group object.
position: A position in a group object.

DESCRIPTION

The TQ3XGroupRemovePositionMethod method deletes the object currently at position position in the group group. It returns the deleted object if successful; otherwise it returns NULL .

TQ3XGroupGetFirstPositionOfTypeMethod

The TQ3XGroupGetFirstPositionOfTypeMethod method gets the position of the first object of a specified type in a group.



 
TQ3Status (*TQ3XGroupGetFirstPositionOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType,

                     TQ3GroupPosition *gPos);

group: A group object.
isType: An object type.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetFirstPositionOfTypeMethod method returns in gPos the position of the first object of type isType in the group group. It returns kQ3Success if successful and kQ3Failure if there is no object of type isType in the group.

TQ3XGroupGetLastPositionOfTypeMethod

The TQ3XGroupGetLastPositionOfTypeMethod method gets the position of the last object of a specified type in a group.



 
TQ3Status (*TQ3XGroupGetLastPositionOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType,

                     TQ3GroupPosition *gPos);

group: A group object.
isType: An object type.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetLastPositionOfTypeMethod method returns in gPos the position of the last object of type isType in the group group. It returns kQ3Success if successful and kQ3Failure if there is no object of type isType in the group.

TQ3XGroupGetNextPositionOfTypeMethod

The TQ3XGroupGetNextPositionOfTypeMethod method gets the position of the next object of a specified type in a group.



 
TQ3Status (*TQ3XGroupGetNextPositionOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType,

                     TQ3GroupPosition *gPos);

group: A group object.
isType: An object type.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetNextPositionOfTypeMethod method returns in gPos the position of the next object of type isType after gPos in the group group. On exit, gPos contains NULL if there is no succeeding object of type isType.

TQ3XGroupGetPrevPositionOfTypeMethod

The TQ3XGroupGetPrevPositionOfTypeMethod method gets the position of the previous object of a specified type in a group.



 
TQ3Status (*TQ3XGroupGetPrevPositionOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType,

                     TQ3GroupPosition *gPos);

group: A group object.
isType: An object type.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetPrevPositionOfTypeMethod method returns in gPos the position of the previous object of type isType before gPos in the group group. On exit, gPos contains NULL if there is no prior object of type isType.

TQ3XGroupCountObjectsOfTypeMethod

The TQ3XGroupCountObjectsOfTypeMethod method returns the number of objects of a specified type in a group.



 
TQ3Status (*TQ3XGroupCountObjectsOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType,

                     unsigned long *nObjects);

group: A group object.
isType: An object type.
nObjects: The number of objects of the given type in the group.

DESCRIPTION

The TQ3XGroupCountObjectsOfTypeMethod method returns in nObjects the count of the number of objects of type isType in the group group.

TQ3XGroupEmptyObjectsOfTypeMethod

The TQ3XGroupEmptyObjectsOfTypeMethod method disposes of all the objects of a specified type in a group.



 
TQ3Status (*TQ3XGroupEmptyObjectsOfTypeMethod) (

                     TQ3GroupObject group,

                     TQ3ObjectType isType);

group: A group object.
isType: An object type.

DESCRIPTION

The TQ3XGroupEmptyObjectsOfTypeMethod method disposes of all the objects of type isType in the group group.

TQ3XGroupGetFirstObjectPositionMethod

The TQ3XGroupGetFirstObjectPositionMethod method gets the position of the first instance of an object in a group.



 
TQ3Status (*TQ3XGroupGetFirstObjectPositionMethod) (

                     TQ3GroupObject group,

                     TQ3Object object,

                     TQ3GroupPosition *gPos);

group: A group object.
object: An object.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetFirstObjectPositionMethod method returns in gPos the position of the first instance of object object in the group group. It returns kQ3Success if successful and kQ3Failure if there is no instance of object object in the group.

TQ3XGroupGetLastObjectPositionMethod

The TQ3XGroupGetLastObjectPositionMethod method gets the position of the last instance of an object in a group.



 
TQ3Status (*TQ3XGroupGetLastObjectPositionMethod) (

                     TQ3GroupObject group,

                     TQ3Object object,

                     TQ3GroupPosition *gPos);

group: A group object.
object: An object.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetLastObjectPositionMethod method returns in gPos the position of the last instance of object object in the group group. It returns kQ3Success if successful and kQ3Failure if there is no instance of object object in the group.

TQ3XGroupGetNextObjectPositionMethod

The TQ3XGroupGetNextObjectPositionMethod method gets the position of the next instance of an object in a group.



 
TQ3Status (*TQ3XGroupGetNextObjectPositionMethod) (

                     TQ3GroupObject group,

                     TQ3Object object,

                     TQ3GroupPosition *gPos);

group: A group object.
object: An object.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetNextObjectPositionMethod method returns in gPos the position of the next instance of object object after gPos in the group group. On exit, gPos contains NULL if there is no succeeding instance of object object.

TQ3XGroupGetPrevObjectPositionMethod

The TQ3XGroupGetPrevObjectPositionMethod method gets the position of the previous instance of an object in a group.



 
TQ3Status (*TQ3XGroupGetPrevObjectPositionMethod) (

                     TQ3GroupObject group,

                     TQ3Object object,

                     TQ3GroupPosition *gPos);

group: A group object.
object: An object.
gPos: A position in a group object.

DESCRIPTION

The TQ3XGroupGetPrevObjectPositionMethod method returns in gPos the position of the previous instance of object object before gPos in the group group. On exit, gPos contains NULL if there is no prior instance of object object.

TQ3XMethodTypeGroupPositionSize

The TQ3XMethodTypeGroupPositionSize method gets the size of your group position private data.



 
unsigned long TQ3XMethodTypeGroupPositionSize;

DESCRIPTION

The TQ3XMethodTypeGroupPositionSize method returns the size in bytes of your group position private data.

TQ3XGroupPositionNewMethod

The TQ3XGroupPositionNewMethod method makes a new group position in a group object.



 
TQ3Status (*TQ3XGroupPositionNewMethod) (

                     void *gPos,

                     TQ3Object object,

                     const void *initData);

gPos: A position in a group object.
object: An object.
initData: Data with which to initialize the position.

DESCRIPTION

The TQ3XGroupPositionNewMethod method creates a new position gPos in the object object, initializing it with the data in initData.

TQ3XGroupPositionCopyMethod

The TQ3XGroupPositionCopyMethod method copies a group position in a group object.



 
TQ3Status (*TQ3XGroupPositionCopyMethod) (

                     void *srcGPos,

                     void *dstGPos);

srcGPos: The position to be copied from.
srcGPos: The position to be copied into.

DESCRIPTION

The TQ3XGroupPositionCopyMethod method copies position srcGPos in the group object into position srcGPos.

TQ3XGroupPositionDeleteMethod

The TQ3XGroupPositionDeleteMethod method deletes a group position in a group object.



 
TQ3Status (*TQ3XGroupPositionDeleteMethod) (void *gPos);

gPos: The position to be deleted.

DESCRIPTION

The TQ3XGroupPositionDeleteMethod method deletes position gPos in the group object.

TQ3XGroupStartIterateMethod

The TQ3XGroupStartIterateMethod method helps draw a view by iteration. It is called once when drawing begins and returns the first object to be drawn.



 
TQ3Status (*TQ3XGroupStartIterateMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition *iterator,

                     TQ3Object *object,

                     TQ3ViewObject view);

group: A group object.
iterator: An iteration position in the group.
object: An object to be drawn.
view: A view.

DESCRIPTION

The TQ3XGroupStartIterateMethod method finds the first object to be drawn in view and returns it in the object parameter. If the returned object value is NULL , then GroupEndIterate will not be called. The iterator parameter is uninitialized when GroupStartIterate is called.

EXAMPLE



 
TQ3Status GroupStartIterate(

    TQ3GroupObject      group,

    TQ3GroupPosition    *iterator,

    TQ3Object           *object,

    TQ3ViewObject       view)

{

    // initialize gPos and object

    *iterator   = NULL;

    *object     = NULL;



 
    // get position of first object in group

    if (Q3Group_GetFirstPosition(group, iterator) == kQ3Failure)

        return kQ3Failure;



 
    if (*iterator == NULL)

        return kQ3Success;



 
    // get first object in group

    if (Q3Group_GetPositionObject(group, *iterator, object) 

        == kQ3Failure)

            return kQ3Failure;



 
    return kQ3Success;

}

TQ3XGroupEndIterateMethod

The TQ3XGroupEndIterateMethod method helps draw a view by iteration. It is called repeatedly while a group is traversed, returning the next object to be drawn each time.



 
TQ3Status (*TQ3XGroupEndIterateMethod) (

                     TQ3GroupObject group,

                     TQ3GroupPosition *iterator,

                     TQ3Object *object,

                     TQ3ViewObject view);

group: A group object.
iterator: An iteration position in the group.
object: An object to be drawn.
view: A view.

DESCRIPTION

The TQ3XGroupEndIterateMethod method is called repeatedly with the previous object and iterator values. It returns in object the next object to be drawn, or NULL when when there are no more objects to be drawn. It is your responsibility to dispose of object .

EXAMPLE



 
TQ3Status GroupEndIterate(

    TQ3GroupObject      group,

    TQ3GroupPosition    *iterator,

    TQ3Object           *object,

    TQ3ViewObject       view)

{

    if (*object != NULL) {

        // dispose previous object

        Q3Object_Dispose(*object);

        *object = NULL;



 
        // get position of next object in group

        if (Q3Group_GetNextPosition(group, iterator) == kQ3Failure)

            return kQ3Failure;



 
        if (*iterator == NULL)

            return kQ3Success;



 
        // get next object in group

        return Q3Group_GetPositionObject(group, *iterator, object);



 
    } else {

        *iterator = NULL;

        return kQ3Success;

        }

}

TQ3XGroupEndReadMethod

The TQ3XGroupEndReadMethod method is a cleanup method that is called when a group has been completely read.



 
TQ3Status (*TQ3XGroupEndReadMethod) (TQ3GroupObject group);

group: A group object.

DESCRIPTION

The TQ3XGroupEndReadMethod method performs validation for the group group and cleans up any memory caches used for reading.